Skip to content

feat(imshow): support facet_row for subplot rows (plotly>=6.7)#82

Merged
FBumann merged 1 commit into
mainfrom
feat/imshow-facet-row
Jun 3, 2026
Merged

feat(imshow): support facet_row for subplot rows (plotly>=6.7)#82
FBumann merged 1 commit into
mainfrom
feat/imshow-facet-row

Conversation

@FBumann
Copy link
Copy Markdown
Owner

@FBumann FBumann commented Jun 3, 2026 •
edited
Loading

Summary

px.imshow gained facet_row support in plotly 6.7.0 (plotly/plotly.py#5445). This PR ports it into xarray_plotly.imshow.

  • Add facet_row to the imshow slot order: ("y", "x", "facet_col", "facet_row", "animation_frame") — now consistent with all other plot types
  • New facet_row parameter on plotting.imshow() and DataArray.plotly.imshow()
  • Global color bounds (zmin/zmax) apply across the full facet grid, as before
  • Docs: fixed the slot table in dimensions.ipynb (it already listed facet_row aspirationally) and added a heatmap-grid example

Compatibility

The plotly requirement stays at >=5.0.0:

plotly >= 6.7.0 plotly < 6.7.0
4D auto-assignment 4th dim → facet_row 4th dim → animation_frame (unchanged)
Explicit facet_row="dim" facet grid informative ValueError suggesting upgrade

Auto-assignment only fills facet_row when the installed plotly supports it, so existing code keeps working on older plotly versions.

Test plan

  • New tests: 4D/5D slot auto-assignment, explicit facet_row, facet grid + animation, shared color bounds across facets, old-plotly fallback and error paths (pytest: 154 passed)
  • ruff, ruff format, mypy clean
  • facet_row tests are skipped automatically when plotly <6.7.0 is installed

🤖 Generated with Claude Code

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 3, 2026 •
edited
Loading

Review Change Stack

📝 Walkthrough

Walkthrough

This PR adds facet_row support to the imshow plotting function. The implementation includes runtime detection of Plotly version support (>= 6.7.0), conditional error handling with informative messages, updates to the public accessor API, configuration changes to default slot ordering, and comprehensive test coverage with documentation examples.

Changes

imshow facet_row feature

Layer / File(s) Summary
Core facet_row implementation in imshow
xarray_plotly/plotting.py		 Adds inspect module for signature detection, introduces _imshow_supports_facet_row() helper that checks Plotly version at runtime, extends imshow signature to accept facet_row parameter, validates support and raises ValueError with upgrade guidance if unsupported, adjusts transpose order to include facet_row when present, and passes it to px.imshow via kwargs dict.
Public accessor API and configuration
xarray_plotly/accessor.py, xarray_plotly/config.py		 DataArrayPlotlyAccessor.imshow method signature updated with facet_row parameter and documented Plotly >= 6.7.0 requirement; call to plotting.imshow passes through the facet_row value; DEFAULT_SLOT_ORDERS["imshow"] updated to include "facet_row" between "facet_col" and "animation_frame".
Slot assignment unit tests
tests/test_common.py		 New test cases verify that 4D and 5D DataArrays correctly assign facet_row and animation_frame dimensions via assign_slots for imshow plots; SLOT_ORDERS["imshow"] expectation updated to include facet_row in the sequence.
Accessor imshow faceting integration tests
tests/test_accessor.py		 Test imports updated to pull plotting and _imshow_supports_facet_row; new pytest skip marker requires_imshow_facet_row gates facet_row tests on version support; new TestImshowFaceting class validates subplot counts, annotations, shared color bounds, combined animation behavior, and error handling when facet_row is unsupported or used on old Plotly; confirms backward compatibility with facet_row=None.
Documentation and examples
docs/examples/dimensions.ipynb		 "Available Slots" table updated to reflect corrected slot order y, x, facet_col, facet_row, animation_frame for imshow; new code example in "Faceting" section demonstrates heatmap gridding with facet_row="metric" on 3D data with inline note requiring Plotly >= 6.7.0.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A plotly heatmap now facets with grace,
With rows to partition and grid to embrace,
Version-gated kindly for Plotly's new way,
Tests guard every path, from old to today! 📊

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: adding facet_row support to imshow with the version requirement, matching the primary objective of the PR.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/imshow-facet-row

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@FBumann @claude
feat(imshow): support facet_row for subplot rows (plotly>=6.7)
34b9799 
px.imshow gained facet_row support in plotly 6.7.0. Add it to the imshow
slot order (y, x, facet_col, facet_row, animation_frame), consistent with
all other plot types.

On older plotly versions, auto-assignment skips the facet_row slot so
behavior is unchanged (the fourth dimension still animates); explicitly
requesting facet_row raises an informative error.

Note: with plotly>=6.7.0, 4D DataArrays now auto-assign their fourth
dimension to facet_row instead of animation_frame.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@FBumann FBumann force-pushed the feat/imshow-facet-row branch from ee2f904 to 34b9799 Compare June 3, 2026 07:34
@FBumann FBumann merged commit 55b503b into main Jun 3, 2026
10 of 11 checks passed
@fluxopt-release fluxopt-release Bot mentioned this pull request Jun 3, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@FBumann